ATOM Documentation

← Back to App

Atom Personal Edition - Installation Guide

Atom Personal Edition is your AI companion for local automation and Telegram control. This guide walks you through installation and setup.

Quick Start (One-Line Install)

**macOS / Linux:**

curl -sSL https://get.atom.ai/install | bash

This will:

  • Download the desktop app
  • Install the atom CLI tool
  • Create desktop shortcuts (Linux)

System Requirements

Minimum

  • **OS:** macOS 12+, Ubuntu 20.04+, or other Linux distributions
  • **RAM:** 4GB
  • **Storage:** 500MB
  • **Network:** Internet connection for LLM API calls

Recommended

  • **RAM:** 8GB+
  • **Storage:** 2GB+
  • **Docker:** Installed for container-based skills

Installation Methods

Method 1: One-Line Install (Recommended)

curl -sSL https://get.atom.ai/install | bash

After installation:

# Start the app
atom start

# Check status
atom status

# View logs
atom logs

Method 2: Manual Download

  1. Download the latest release for your platform:
  1. Extract the archive:
  1. Run the app:

Method 3: Build from Source

# Clone repository
git clone https://github.com/atom-saas/atom-personal.git
cd atom-personal

# Install dependencies
npm install

# Run dev mode
npm run tauri dev

# Build for production
npm run tauri build

Setup Steps

1. Create Your Account

Visit https://app.atom.ai/signup and create a Personal Edition account.

Or use the CLI:

atom signup

2. Link Telegram

**Why link Telegram?**

  • Control your agent from anywhere
  • Get real-time status updates
  • Send commands via chat

**Steps:**

  1. Open the Atom app
  2. Go to Settings > IM
  3. Click "Link Telegram"
  4. Open Telegram and search for @AtomAgentBot
  5. Send the command: /link YOUR_TOKEN
  6. Confirm the linking

3. Create Your First Agent

  1. Click "Create Agent" in the app
  2. Choose a name (e.g., "Jarvis")
  3. Select a role (Assistant is good for general use)
  4. Click "Create"

Your agent is now ready!

Using Your Agent

Via Desktop App

The desktop app provides:

  • Chat interface
  • Agent status dashboard
  • Settings and configuration
  • Logs and debugging

Via Telegram

Once linked, you can interact with your agent via Telegram:

/status                    # Check agent status
/help                      # List available commands
Hello, what can you do?    # Chat with your agent
Run system update          # Execute a shell command (requires approval)

Via CLI

# List agents
atom agent list

# Run agent skill
atom agent run <agent-id> --task "Check system status"

# View agent logs
atom logs --agent <agent-id>

Features & Limitations

Personal Edition Features

FeatureAvailable
Local Agent✅
Telegram IM✅
Shell Execution✅ (with approval)
Agent Skills✅
Chat Interface✅
Desktop App✅
Multi-User❌
WhatsApp IM❌
Signal IM❌
Agent Feed❌
API Access❌
Webhooks❌

Maturity Levels

Personal Edition supports up to **Supervised** maturity:

  • **Student:** Read-only, safe operations
  • **Intern:** Medium complexity, requires proposals
  • **Supervised:** Most operations with human oversight
  • **Autonomous:** ❌ Not available in Personal Edition

Configuration

Shell Access

By default, shell commands require approval. To change this:

  1. Go to Settings > Shell
  2. Choose approval mode:
  • **Always:** Every command requires approval
  • **First Only:** Approve once per command type
  • **Trusted:** No approval (not recommended)

Telegram Commands

Customize Telegram commands in Settings > IM > Commands.

Agent Settings

Adjust agent behavior in Settings > Agent:

  • Maturity level
  • Default timeout
  • Skill permissions

Troubleshooting

App Won't Start

**Check logs:**

atom logs

**Common issues:**

  • Port 3000 already in use → Change port in Settings
  • Docker not running → Start Docker daemon
  • LLM API key missing → Add key in Settings

Telegram Link Fails

**Check:**

  1. Token is correct (copy fresh from Settings)
  2. Bot username is @AtomAgentBot (exact spelling)
  3. Telegram account is not blocked

Agent Not Responding

**Debug:**

  1. Check agent status: atom status
  2. View agent logs: atom logs --agent <id>
  3. Verify LLM API key is valid
  4. Check internet connection

Shell Commands Fail

**Check:**

  1. Approval was granted (check Telegram/app)
  2. Command is in allowed list (Settings > Shell)
  3. Agent maturity level permits command
  4. Path is safe (no dangerous directories)

Upgrading to Enterprise

Need more features? Upgrade to Enterprise Edition:

  • Multi-user support
  • All IM platforms (WhatsApp, Signal)
  • Agent social feed
  • API access and webhooks
  • Advanced analytics

Visit https://app.atom.ai/upgrade to learn more.

Uninstall

**Remove Atom Personal:**

# Stop the app
atom stop

# Remove installation directory
rm -rf ~/.atom

# Remove PATH entries
# Edit ~/.bashrc or ~/.zshrc and remove the atom line

# Remove desktop entry (Linux)
rm ~/.local/share/applications/atom-personal.desktop

Support

  • **Documentation:** https://docs.atom.ai
  • **Issues:** https://github.com/atom-saas/atom-personal/issues
  • **Community:** https://discord.gg/atom-ai
  • **Email:** support@atom.ai

License

Atom Personal Edition is licensed under the MIT License. See LICENSE file for details.